Table of contents
General information   License Issues   Year 2000 issues   Introduction   About the author	User's Manual   Basic functions   Advanced functions   The response file   Using...   Syntax...   The built-in help

 

License Issues

This version of INIWorks is distributed as SHAREWARE. You may use the program unlimitedly for 60 days at which time you have to decide to eighter discard the program or register it. You are encouraged to distribute the unregistered version of INIWorks as long as the package is not modified. At the end of the evaluation period, you must destroy all your copies of INIWorks. The registration fee is 5 USD, which is best sent via snail mail after contacting the author via email at lrd@plea.se. Please keep an eye on the home site of INIWorks for news on purchasing and licensing. By registering INIWorks, you gain a single user license to the product and you help the author to make even better products. Registered users also have access to support for the product via email. All registered users have right to all new versions of INIWorks as long as the license is valid. Upon registering, the user receives a personalized version of the program which has different license conditions. This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantibility or fitness for a particular purpose. The user should be aware of the risks of manipulating the windows initialization files. Careless changes to some ini files may render the system unusable. The author of INIWorks accepts no responsibility for any loss of functionality or loss of data as result of the use of this product. Windows is a registered trademark of Microsoft Corporation.

Year 2000 issues
INIWorks doesn't use any date structures or operations in its source code. There are no date related checks or comparisons of any kind for the functions described in this manual. This should keep INIWorks unaffected by the year 2000 issue.

Introduction

INIWorks is a utility for manipulating Windows(TM) INI files from the command line. It begun its life as freeware and made it to 1.1. At that time the functionality of the program was very simple and the code was really not nice. With some more ideas and some user input. INIWorks grew over the years to be able to do most of what a power user should want from a program of this kind. The canonical INIWorks command line: C:\> INIWorks <operation> <ini file name> <data> <data> <data> The program is started with an operation name and parameters (data) for this operation. Each operation has a more or less verbose name, which may make them easier to remember. Most of the operations have a shorter, one character name too. INIWorks returns 1 on success. I realize that this behaviour does not match the standard DOS behaviour, but this bug just doesn't justify a new update version and distribution. I had no thought on supporting return values, since this is a document reader/writer program; all results can be seen on the standard output. There is a built-in help system with several pages of information on switches. I have tried to arrange the switches in increasing chance of usage, but the main purpose behind using pages is that there are more functions than can be showed on a singe page in DOS. Rather than writing a command for changing one value at a time in an INI file, INIWorks can MERGE two INI files. This is done in a straight forward manner; see the section about --merge. You are very welcome with comments about this program; I am particulary interested in comments about how the program fits different needs. INIWorks has been pretty stable for a long time, so there are very seldom any bugs reported. I encourage you to report any bugs as soon as you have discovered them. Although there are a lot of other INI file manipulating utilities on the Internet, I sincerely believe that this is THE one you need.

About The Author
Laszlo Radanyi works as C/C++ developer at Cell Network Göteborg, Sweden. He can be reached at lrd@plea.se. You can download the latest version of INIWorks and look at the latest revised manual here.

User's Manual

INIWorks is a DOS command-line mode program, and it is aimed at batch use that is, it needs command-line arguments to complete a function. The user has also the option to use a 'response file' to supply arguments to INIWorks. See "The Response File" for more information about this. The arguments used by the program are referenced in this manual by this style. The names used are as follows: ini file name The target INI file name. if this file is in the same directory as INIWorks, only the file name is necessary, otherwise the full path needs to be given. section The target section, that is, the INI value starting after a string enclosed in brackets as in [section] and until the next such section name is encountered. key The string before the first equal sign on one line in the given section. value The string after the first equal sign on one line in the given section. variable The name of the environment variable to use for the -e function. What about section names, key names and values that contain spaces ? INIWorks gets its arguments from the command shell. Since the information on the command line is broken up into words before INIWorks sees them, you have to do an additional step - enclose the string in double quotes. Let's look at an example, where I want to manipulate the key foo in section just a test in INI file foo.ini: C:\> INIWorks r foo.ini "just a test" foo Enclosing the string just a test within double quotes makes sure that INIWorks sees the whole string as one argument - otherwise the string would have been split into three words ! The 'dash' method For all operations that need a value, (like write), you can supply a single dash '-' in place of the value, which tells INIWorks to read the data to be written from the standard input stream. This makes it possible to Read a value into a temporary file Then let INIWorks read this value from the temporary file and do something with it. For example, given a file SOURCE.INI with a section foo and key bar, you could do as follows: C:\> INIWorks read SOURCE.INI foo bar > TMPFILE.DAT then you could write the read value into the file TARGET.INI, key foo2 and key bar2: C:\> INIWorks write TARGET.INI foo2 bar2 - < TMPFILE.DAT C:\> DEL TMPFILE.DAT >NUL NOTE to current users: The master environment functions are now removed from this version and there will be no more support for them. As you'd probably expect, the dash method also works when combined with a response file.

Basic functions

The basic functions are the most used or oldest functions; they are probably what you would expect from a program like this. h or help This launches the the built-in help system v or version Prints version information along with registration data to the standard output stream. The version information is necessary when communicating with the author. This can also help you to see if there is a newer version distributed. Newer versions are generally better since the reported bugs are always corrected before new functionality is added. With access to the net, you can always check for the latest version of INIWorks by looking at the header of the INIWorks manual r or read Prints value of key to the standard output stream. w or write Changes an existing key value as specified; if the key doesn't exist, a new key is created. a or append Appends value to the current value of key. If the key doesn't exist, a new key is created. i or insert or prepend Inserts value immediately after the equal sign '=' of key. If the key doesn't exist, a new key is created. d or delete Removes key from section. m or merge Writes the contents of source file into target file just as you would write value for value. Please pay attention to that merge does not handle SYSTEM.INI/[386Enh] very well, since it uses standard INI file write operations; that is, for each section, for each key in the source file, it writes [Section]/key=value into the target file. This means that the first device= statement could be over written several times.

Advanced functions

c or comment Inserts a comment character ';' before the entry. q or write_quoted Writes value inside of double quotes. For example: C:\> INIWorks q TEST.INI section key value_to_be_quoted results in the following entry written into the file TEST.INI in the same directory as INIWorks.EXE: [section] key="value_to_be_quoted" Just setting the value within quotes on the command line won't make INIWorks read the quoted value. That is because of the command shell, which uses the quotes internally. (There is more about double quotes and INIWorks, you can read about it here) When you use the '-' value specification or when you use a response file, INIWorks can read even a quoted value, in which case the q option is not necessary. write_blind Writes key=value as first entry in section without search for an already existing value. write_pair Searches for key=value under section and creates the key if it doesn't exist. This is essentially the same function as write, but this one also looks for the supplied value; that is: the function does not modify just any key to set its value. All matching keys are searched for their values too, and only if the key/value pair doesn't already exist will an entry be written into the INI file. ** NOTE ** The pair functions all are primarily intended to deal with the [386Enh] section in SYSTEM.INI, since this section contains a lot of keys named 'device' but different values. comment_pair Searches for key=value under section and places a comment character before the key. This is the same function as 'comment' but it also looks for the value. delete_pair Searches for key=value under section and removes the entry. delete_section Removes section from the INI file named <ini file name>. read_section Prints the entire contents of section to the standard output stream. add_to_list This command makes INIWorks look at a value as a comma separated list of values. This construct is common in several INI files of importance. add_to_list will append value to the current list, inserting a list separator (=comma) if necessary. If there was no key or if the key was empty, value will appear by itself as key=value. The value will not be added if it is already in the list. Search for the list elements is case insensitive. remove_from_list Like add_to_list, this command manipulates a list of values. value and its list separator is removed from the list. replace_in_list Like add_to_list, this command manipulates a list of values. The command searches for value and replace it at its current position in the list by value2. If no elements in the list were replaced, value2 will not be appended to the list.

The response file

What a response file is You can use a separate file to give INIWorks the commands it needs. Such a file contains the same information as INIWorks would get from the command line. What you gain is the possibility to supply longer commands and parameters to INIWorks than the command line would permit. Typically, DOS cannot take more than 128 characters. If you need to supply, say, 120 characters, it would be hard to do with INIWorks, since the program name and the switches (or commands) would take some space from the available 128 bytes. Under some environments it would be possible to increase the command line length to much higher values, but a response file could still be useful to reuse tasks. Using a response file You use a response file by giving its path and name to INIWorks as first parameter, lead by a '@' character. Example: C:\> INIWorks @MYRESP.TXT C:\> INIWorks @E:\LIB\CCT.RF The first command would use the file MYRESP.TXT int the current directory for command input, the second would use E:\LIB\CCT.RF since full path to the file is given. Any additional parameters supplied to INIWorks after the response file specifier parameter will be ignored. Response file syntax Each line in the response file contains one 'word' from an imaginate command line. Suppose you have an INIWorks command like this: C:\> INIWorks r c:\windows\win.ini desktop wallpaper A command line using a response file named INIWorksR.TXT in the current directory would look like this: C:\>INIWorks @INIWorksR.TXT and the contents of this file: r c:\windows\win.ini desktop wallpaper In addition to parameters, you can comment your parameters. Any line starting with a ';' character will be skipped by INIWorks. Empty lines are also skipped, so it's possible to have a response file like this: ; my settings: bla bla bla w ; ; bla bla blabla bla blabla bla blabla bla bla T.INI ; ;bla bla blabla bla bla foo bar

The built-in help

The built-in help is invoked by issuing the command 'INIWorks' alone on the command line or by giving eighter of the '?' 'h' options. Help consists of three pages, BASIC, ADVANCED and MISCELLANEOUS. All pages are just written to the standard output. INIWorks waits for a keystroke on all screens; you can go to eighter page by pressing '1' (ONE) '2', or '3'. You exit help by pressing any other key than '1','2' or '3'.